NAME
   DL_DataGetFromUniqueRecordId,
   CSSM_DL_DataGetFromUniqueRecordId - Get data record (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_DL_DataGetFromUniqueRecordId
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord,
        CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
        CSSM_DATA_PTR Data)
    SPI:
        CSSM_RETURN CSSMDLI DL_DataGetFromUniqueRecordId
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord,
        CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
        CSSM_DATA_PTR Data)

 LIBRARY
   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 PARAMETERS
   DLDBHandle (input)
           The handle pair that describes the add-in data storage
           library module to be used to perform this function and the
           open data store to search for the data record.

   UniqueRecord (input)
           The pointer to a unique record structure returned from a
           DL_DataInsert, DL_DataGetFirst, or DL_DataGetNext operation.

   Attributes (optional-input/output)
           If the Attributes structure pointer is NULL, no values are
           returned.

           Otherwise, the DataRecordType, NumberOfAttributes and
           AttributeData fields are read.  AttributeData must be an
           array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE
           elements. Only the Info field of each element is used on
           input. The AttributeFormat field of the Info field is
           ignored on input.

           On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing
           a list of all or the requested attribute values (subset)
           from the retrieved record.  The SemanticInformation field
           is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the
           AttributeData array, the NumberOfValues field is set to
           reflect the size of the Value array which is allocated by
           the DL using the application specified allocators.  Each
           CSSM_DATA in the Value array will have it's Data field as a
           pointer to data allocated using the application specified
           allocators containing the attributes value, and have it's
           Length set to the length of the value.

           All values for an attribute are returned (this could be 0).
           All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA
           are left unchanged except for the AttributeFormat field,
           which is set to reflect the schema.

   Data (optional-input/output)
           Data values contained in the referenced memory are ignored
           during processing and are overwritten with the retrieved
           opaque object. On output, a CSSM_DATA structure containing
           the opaque object stored in the retrieved record. If the
           pointer is data structure pointer is NULL, the opaque object
           is not returned.

 DESCRIPTION
   This function retrieves the data record and attributes associated
   with this unique record identifier. The Attributes parameter can
   specify a subset of the attributes to be returned. If Attributes
   specifies an attribute that is not defined in the database's meta-
   information, an error condition is returned. The output buffers for
   the retrieved record are allocated by this function using the memory
   management functions provided during the module attach operation.
   The DL module can use an indexing structure identified in the
   UniqueRecordId to enhance the performance of the retrieval operation.

   The DL should assume that the value of CSSM_QUERY_FLAGS is when
   performing this operation. In particular this means that if the
   data of a key record is being retrieved, the DL will return a
   CSSM_KEY structure with a key reference.

   If the record referenced by UniqueRecordIdentifier has been modified
   since the last time it was retrieved, the error (warning)
   CSSMERR_DL_RECORD_MODIFIED is returned but the requested attributes
   and data of the new record is returned. The caller should be advised
   that other attributes (or the data) might have changed that were not
   fetched from the DL with this call.

 RETURN VALUE
   A CSSM_RETURN value indicating success or specifying a particular
   error condition. The value CSSM_OK indicates success. All other
   values represent an error condition.

 ERRORS
   Errors are described in the CDSA technical standard.  See CDSA.

        CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
        CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
        CSSMERR_DL_INVALID_DB_HANDLE
        CSSMERR_DL_INVALID_FIELD_NAME
        CSSMERR_DL_INVALID_RECORDTYPE
        CSSMERR_DL_INVALID_RECORD_UID

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_DL_DataInsert
       CSSM_DL_DataGetFirst
       CSSM_DL_DataGetNext

   Functions for the DL SPI:

       CSSM_DL_DataInsert
       CSSM_DL_DataGetFirst
       CSSM_DL_DataGetNext